Using the examples

The SDK comes with a few default examples to get started. These can be used to practice building and running custom code, as well as for reference when creating new projects. These can be found within the SDK installation under the examples folder. The developer shell begins in this directory by default.

The main use of the developer shell is to compile code, so a good first step is to practice by compiling the examples. There are a few ways to do this.

1) Build a Single Example

To build a single example, use the bmake command and pass it the make (.mke) file for the project. This is the same process for building individual custom projects written by users

To demonstrate, building the ManagedSDKExample project requires the following command and produces the following output

bmake ManagedSDKExample/ManagedSDKExample.mke

The output shows that the example built successfully, so now it is ready to run within OpenRoads Designer.

Note: To debug examples written with the Managed SDK, they must be built within Visual Studio. This is covered in the Debugging a Managed Project section.

2) Build All Examples

To build all the default examples, run the BuildAllExamples.bat file inside the example’s directory

This script will cycle through every project in the example's directory of the SDK installation and build it

1. Running Custom Projects in OpenRoads Designer

Once a project is built through the developer shell, it can be run in OpenRoads Designer. This is done by loading the project as a Key-In. Creating projects that can be built and run this way is discussed later, but for now let's cover how to load one of the existing examples.

The ManagedSDKExample is a managed project, which means it's written using the managed SDK and outputs a DLL and PDB file. An unmanaged SDK project will output a DLL, PDB, and MA file.

When built, these output files are stored in the Mdlapps folder within the OpenRoads Designer installation. This can be found under:

OpenRoads Designer CONNNECT Edition\OpenRoadsDesigner\Mdlapps

With the files in this location, the project can be found and loaded as a Key-In. To do this, open the OpenRoads Designer CONNECT Edition application. Access the Key-In menu under the Home tab:

Load the project using the mdl load Key-In, passing in the name of the project as the argument. The command to load the ManagedSDKExample project is as follows:

mdl load ManagedSDKExample

If successful, the message "MANAGEDSDKEXAMPLE loaded." will appear at the bottom of the application in the status bar. The Key-In is now loaded and ready for use with the MANAGEDSDKEXAMPLE command. Any further commands specified within the Key-In can be run from this root command (this command hierarchy will be explained later).

2. Overview of Provided Examples

There are two main examples provided with the SDK installation - the Managed SDK Example and the Unmanaged SDK Example. These examples illustrate how to use some common, basic functionality of the SDK. For detailed explanation of the files included in the Managed and Unmanaged SDK Examples, view the later sections on developing with each one.

Managed SDK Examples

The example files below are located within the ManagedSDKExample solution under the Examples folder.

Class	Key-in	Method
ArcCreator.cs	ManagedSDKExample>Create>HorizontalAlignments>Arc	CreateArcFromPoints()
The user is prompted for three points. The first two are linked by a temporarily drawn line. After the third point, an arc is created with the three points.

Class	Key-in	Method
ComplexAlignmentCreator.cs	ManagedSDKExample>Create>HorizontalAlignments>Complex Alignment	CreateComplexAlignmentFromPoints()
The user places two data points. A complex horizontal alignment is created using these two points as a start line, with a start spiral, arc, end spiral, and end line. The direction and line length are determined by the user's points.

Class	Key-in	Method
CorridorItemsComplexAlignmentCreator.cs	ManagedSDKExample > Create > CorridorItems > Complex Alignment	CreateAlignment()
The user places multiple data points and a complex horizontal alignment is created which contains multiple straight lines.

Class	Key-in	Method
CorridorItemsCorridorCreator.cs	ManagedSDKExample > Create > CorridorItems > Corridor	CreateCorridor()
The user selects a horizontal alignment which contains an active profile, and the command creates a corridor.

Class	Key-in	Method
CorridorItemsFeatureDefinitionSet.cs	ManagedSDKExample > Create > CorridorItems > SetFeatureDefinition	SetFeatureDefinition()
The user selects a horizontal alignment and a feature definition, which is then applied to the alignment.

Class	Key-in	Method
CorridorItemsProfileCreator.cs	ManagedSDKExample > Create > CorridorItems > Profile	CreateProfile()
The user selects a horizontal alignment for which to create a vertical alignment. The user is prompted for a constant elevation and a feature definition, then a vertical alignment is created using these values.

Class	Key-in	Method
CorridorReporter.cs	ManagedSDKExample > Report > Corridors	ReportAllCorridors()
Generates a report of all corridor components including: Name Feature name Slope Area Volume

Class	Key-in	Method
HorizontalAlignmentCreator.cs	ManagedSDKExample > Create > HorizontalAlignments ManagedSDKExample > Create > HorizontalAlignments > Line	CreateAlignmentFromPoints()
The user selects a feature definition and name, places data points, and then right-clicks to complete the command which creates a complex horizontal alignment with the given information. Both Key-Ins above call the same function.

Class	Key-in	Method
HorizontalAlignmentReporter.cs	ManagedSDKExample > Report > HorizontalAlignments	ReportAllAlignments()
Reads all alignments and reports information based on the element types in each one. Data reported for each element type can be found in the same file inside the AlignmentPropertyReader class in the ReadLine(), ReadSpiral(), and ReadCircularArc() functions.

Class	Key-in	Method
HorizontalAlignmentReporter.cs	ManagedSDKExample > Report > HorizontalAlignments > AsAnnotation	AnnotateAllAlignments()
Reports the same information but displays it as annotations on the reported alignments. The functionality for displaying data this way is in the solution under \Utility\DataDisplayHelper.cs in the AnnotationHelper class.

Class	Key-in	Method
HorizontalCurbReturns.cs	ManagedSDKExample > Create > HorizontalAlignments > Curb Returns	CreateLinesFromPoints()
The user places four data points, representing two intersecting lines. The lines are offset by a specified radius to create the center of an arc. The arc is created from the given radius, and the command returns the beginning of the first line, the arc, and the end of the second line.

Class	Key-in	Method
PIAlignmentCreator.cs	ManagedSDKExample > Create > HorizontalAlignments > PI Alignment	CreatePIAlignmentFromPoints()
The user is prompted to place points which are temporarily linked by a line. The user is also prompted for the arc radius, feature definition, start and end spiral lengths for the next angle. At the end of the command, a complex horizontal alignment is created from the data with a curve set at each PI.

Class	Key-in	Method
PickAlignmentTool.cs	ManagedSDKExample > Report > HorizontalAlignments > PickAlignment	OnDataButton()
This tool allows the user to select an alignment then generates a report on that alignment using the Horizontal Alignment Reporter (discussed earlier). This example illustrates how to get the cursor position and obtain a selected element.

Class	Key-in	Method
SpiralCreator.cs	ManagedSDKExample > Create > HorizontalAlignments > Spiral	CreateSpiralFromPoints()
The user places a single point and a spiral is created from that point.

Class	Key-in	Method
TerrainReporter.cs	ManagedSDKExample > Report > StationOffsetElevation	StationOffsetElevation()
Reads alignments and creates a report of the terrain elevations at an interval. The report includes: Horizontal Alignment Name Active Vertical Alignment Name Station, Offset, Northing, Easting, Elevation etc

Class

Key-in

Method

TerrainReporter.cs

ManagedSDKExample > Report > DrapeLineAtInterval

DrapeLineAtInterval()

Reads alignments and creates a report of the draped cross-section lines at given offsets and intervals. Report includes:

File Name
Model Name
Active Terrain Name
Horizontal Alignment
Active Vertical Alignment

Station
Offset
Elevation
Easting
Northing

Class	Key-in	Method
QQChecker.cs	ManagedSDKExample > Report > QQChecker	OnDataButton()
This tool allows the user to select an alignment then generates a report of the difference between the terrain and alignment elevations.

Class	Key-in	Method
VerticalAlignmentCreator.cs	ManagedSDKExample > Create > VerticalAlignments ManagedSDKExample > Create > VerticalAlignments > Line	CreateVerticalAlignment()
The user selects a horizontal alignment for which to create a complex vertical alignment. The user then places points within their chosen profile view, which are temporarily linked by a visible line. When the command ends, a complex vertical alignment is created from the points. Both Key-Ins above call the same function.

Class	Key-in	Method
VerticalAlignmentReporter.cs	ManagedSDKExample > Report > StationElevations	StationElevationsReport()
Reads profiles and creates a report of stations and elevations at an interval. Report includes: Profile Name Length

Class	Key-in	Method
VerticalAlignmentReporter.cs	ManagedSDKExample > Report > ActiveStationElevation	ActiveStationElevationAtIntervalReport()
Reads active profiles and creates a report of stations and elevations at an interval, as well as cardinal points. Report includes: File Name, Model Name Horizontal Alignment Active Vertical Alignment Name Station Point Type, Station, Elevation etc.

Class

Key-in

Method

VerticalAlignmentReporter.cs

ManagedSDKExample > Report > ActiveStationElevation

ActiveStationElevationAtIntervalReport()

Reads active profiles and creates a report of stations and elevations at an interval, as well as cardinal points. Report includes:

File Name, Model Name
Horizontal Alignment
Active Vertical Alignment Name
Station Point Type, Station, Elevation etc.

Class	Key-in	Method
VerticalAlignmentReporter.cs	ManagedSDKExample > Report > ProfileElements	ProfileElementReport()
Reads profiles and creates a report of profiles and their elements. Data reported depends on the element type - see the ReportProfileLine(), ReportProfileParabola(), and ReportProfilePoint() functions for details.

Class	Key-in	Method
VerticalParabolaCreator.cs	ManagedSDKExample > Create > VerticalAlignments > Parabola	CreateParabola()
The user selects a horizontal alignment with which to create a vertical alignment. The command then creates a vertical parabola with this alignment.

Class	Key-in	Method
VerticalComplexAlignmentCreator.cs	ManagedSDKExample > Create > VerticalAlignments > Complex Alignment	CreateComplexAlignment()
The user selects a horizontal alignment with which to create a vertical alignment. The command then creates a complex vertical alignment made of an entrance tangent, parabola, and exit tangent.

Class	Key-in	Method
WPFToolbar.cs	ManagedSDKExample > WPFToolbar > Open	OpenWindow()
This example would help to show how you can add Dockable WPF toolbar in your Add-In Project. All the necessary linkages are made & added 2 sample buttons which you can change as per your requirements. You can Dock the Toolbar on Top or Bottom area of your OpenRoads Designer.

Class	Key-in	Method
WPFDockableWindow.cs	ManagedSDKExample > WPFWindow> Open	OpenWindow()
This example would help to show how you can add Dockable WPF Window in your Add-In Project. All the necessary linkages are made & added 4 sample buttons which you can change as per your requirements. You can Dock the Window in all 4 Sides of your OpenRoads Designer

Unmanaged SDK Examples

The Unmanaged SDK Example only provides one key-in command. This example reproduces the HorizontalAlignmentReport from the managed example and is mainly provided as a framework for developing future unmanaged SDK projects should you choose to do so.

Class	Key-in	Method
HorizontalAlignmentReporter.cpp	UnmanagedSDKExample > HorizontalAlignmentReport	GenerateReport()
Reads all alignments and reports information based on the element types in each one. Data reported for each element type can be found in the same file in the ReportLine(), ReportSpiral(), and ReportCircularArc() functions.